Index

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Easy Album Manager 1.00 / help file build 1.01

Welcome to the Easy Album Manager help file. I hope you will find it useful. Remember you also have the official website (http://easyam.free.fr and its forum to help you). You can also find resources and updates there, so don't forget to visit it regularly.

You're also invited to participate to the forum, to give your opinion, but also to share your wishes for the next versions, and to report bugs that will be fixed in the shortest delay.

Easy Album Manager was not developed to encourage piracy ! This tool was made to help people who have a lot of audio CDs and enjoy to play their encoded version on their computer.

In this help file, you will find references to the Marillion band, because it's been my favorite band for years now, and you should really listen to their latest releases, don't forget to visit their website http://www.marillion.com.

Quick start

Things to know ...

Windows and dialogs

Create a new playlist

Directories to scan

Playlist management

List window

Built-in audio player

Browse window

Browse options

Album details edition

Search

Filter options

Covers database

Cover picture replacement

Remote commander

Configuration

Export

Template editor

Main menu

File

New list (Ctrl+N)

Load list (Ctrl+0)

Save list (Ctrl+S)

Save list as ...

Close list

Export list

Mp3 CD autoscan

Exit

Edit

Search (Ctrl+H)

Search next ... (F3)

Options (Ctrl+T)

List

Update batch process (Shift+Ctrl+U)

Scan current list (Ctrl+F5)

Fast scan (F5)

Cache all covers

List/Browse view (Ctrl+B)

View folders in list (Shift+Ctrl+B)

Browse mode options

Show/Hide right panel

Add new directories to scan

Delete or move a directory to scan

Filters (Ctrl+F)

Export covers to local CoversDB

Export covers to a CoversDB file

Import covers from local CoversDB (Shift+Ctrl+I)

Most often played albums (Ctrl+F2)

Last played albums (Ctrl+F3)

Artist - Year - Genre

Year ascending

Album

Update with FreeDB (Ctrl+U)

Edit details (Ctrl+D)

Write information in playlist file

Scan album information

Paste image (Shift+Ctrl+V)

Load image

Delete image

Import cover from local CoversDB (Ctrl+I)

Remove album from list

Selection

Create a selection

Edit current selection (Ctrl+E)

Rename selection

Remove selection

Add/Remove selected album (Ctrl+A)

Add all albums to selection (Shift+Ctrl+A)

Playlist

Play album (Ctrl+P)

Play album (external)

Add album to playlist (Shift+Ctrl+P)

Add all albums to playlist

Play track

Play track (external)

Add track to playlist

Load playlist

Save playlist

Clear playlist (Ctrl+Y)

Remove track

Move track up

Move track down

Jump to currently playing album (Ctrl+J)

View remote commander (Ctrl+W)

Tools

Playlist builder (Ctrl+L)

Local CoversDB management (Ctrl+R)

View menu bar (Ctrl+M)

Toolbars management

Quick start
  1. Launch menu [File / New list (Ctrl+N)]
  2. Add new directories to scan dialog : add one or several directories where you use to store your albums (can be the full drive, but the scan will be longer) and click on Ok.
  3. Playlist management : Manually visit each directory and create playlists, one per album, if it's not already done. Then click on Ok when it's completed. The application will perform a scan and list all found albums (playlists) in the List window.
  4. List window
    • For each album where information are missing, edit its details with [Album / Edit details (Ctrl+D)].
    • Add covers, for example by drag'n'dropping images on the cover art area, or pasting from the clipboard (Paste image (Shift+Ctrl+V)).
    • Now save your list [File / Save list as ...]
  5. Browse window : Access the browse window with [List / List/Browse view (Ctrl+B)], and double-click on the album you want to listen !
Things to know
  • Easy Album Manager considers that a .jpg file having the same name as a playlist (.m3u, .pls or .b4s) and located in the same directory as the playlist is its cover art picture. For example, "Marillion - Anoraknophobia (2001).jpg" is the cover art picture of "Marillion - Anoraknophobia (2001).m3u"

  • You can burn mp3 CD/DVDs with one or more .cea file(s) in the root directory. In this case the list will be loaded automatically (one .cea file only) or you will be asked to choose one, and the medium won't need to be scanned (can be long). To do such a thing, with your explorer create a new directory, copy the albums into it, then in Easy Album Managercreate a new list and add this directory in the directories to scan, then scan the directory, add cover arts etc ... and save the file in the root of the directory you created, as a .cea file. You can now burn this directory.
Main menu

File

New list (Ctrl+N)

Creates a new list. The application searches recursively for all playlist files (m3u, lst, b4s) in the Directories to scan : they will be the first thing you'll be asked for.
Then you will enter the Playlist management dialog, in order to build your album playlists, if it's not already the case. When you're happy with the playlist files, the application will perform the full scan, and will extract the artist, album, genre and year information from the audio files tags.

Load list (Ctrl+0)

In order to avoid scanning directories each time you launch the application (it can take a while !), you can save and load list files.
A list file is a .eam file that contains all the scanned information. If you modify an album information (artist, album name, year, genre) you should always tag the audio files of the album (view Album details edition), in order to keep those data saved at the lowest level.
The .eam file also stores other information, like the cached cover arts in order to make the display faster.

Save list (Ctrl+S)

Saves the current changes. You will be asked for a file name if the current list has never been saved.

Save list as ...

To save your current list with a different file name, or to save a list for the first time after a new scan.

You can choose to save a list as a .cea file. The only difference between a .cea and a .eam file is that all file paths (playlists, audio files, images) in a .cea file are stored relatively to .cea file path. This feature will be used if you want to burn a mp3 CD/DVD putting a Easy Album Manager .cea file in the medium root. You can put several .cea files in the root directory. If there is only one, it will be loaded automatically. If there are several ones, you will be asked to choose one.

Close list

Saves (eventually) and closes the current list.

Export list

If you want to export your current list in a text, html, csv ... file please have a look at Export.

Mp3 CD autoscan

If a Mp3 CD/DVD is currently in one of your CD-ROM/DVD-ROM drives, it will automatically be scanned and its list will be created. This operation can be fully automatic, have a look at Configuration.

You can also put a .cea file in the root of your medium, if it is found, the medium won't be scaned and you will save time. Have a look at Things to know.

Exit

Exits Easy Album Manager.

Edit

Search (Ctrl+H)

To search for a string or words in the artist, album title and song titles. View Search.

Search next ... (F3)

When a search is active, goes to the next match.

Configuration (Ctrl+T)

To edit the configuration of Easy Album Manager, have a look at Configuration.

List

Update batch process (Shift+Ctrl+U)

With this option you will be able to launch a batch process on all albums having a red status. Please specify in the dialog box which operations you want to be performed.

Scan current list (Ctrl+U)

A first scan is performed when you create a new list, but after you can perform another one, for example if you changed a lot of things on your file system and want to keep your list synchronized.
This update mode will read again all audio tags and modify the artist, album, genre and year information in the list.
This scan takes time, so prefer the Fast scan option if you simply removed and added albums (and it should be the case most of the time).

Fast scan (Shift+Ctrl+U)

Launch this to keep your list synchronized with your file system, in the case you added new albums or removed ones. This scan won't read again the audio files tag.

Cache all covers

If you activated the cover art caching system (Configuration), cover art previews are saved in the .eam file. This option will put all cover arts in the cache. This way, the browse mode display will be very fast.

List/Browse view (Ctrl+B)

Switch between List and Browse modes.

View folders in list (Shift+Ctrl+B)

This special view will display your albums in a hierarchical folders view. By default, if a folder only has one playlist, this folder won't be displayed. You can change this in Configuration.

Browse mode options

In order to tune your browse mode display, have a look at Browse options.

Show/Hide right panel

If you want to have more space for the albums in list or browse mode.

Add new directories to scan

When building a list, Easy Album Manager scans these directories and searches for album playlists. Have a look at Directories to scan.

Delete or move a directory to scan

To remove a directory from the list of scanned directories, or to indicate to Easy Album Manager that a location has moved. Have a look at Directories to scan.

Filters (Ctrl+F)

In order to display only albums matching strings on the artist, album title, genre or year, see Filter options.

Export covers to local CoversDB

The local CoversDB can store cover arts (for a given artist, album). With this option you will export all the cover arts of your current list to the local CoversDB. It can be considered as a database you can enrich with other people cover arts (have a look at Covers database).

Export covers to a CoversDB file

In this case, you will export your current list cover arts to a file you'll be asked the name for. This way you can send your cover arts to another Easy Album Manager user.

Import covers from local CoversDB (Shift+Ctrl+I)

If you have saved your cover arts to your local CoversDB, or if you have added other users cover arts to your local CoversDB, you may want to update your current list with covers arts from your local CoversDB. You can get cover arts only for albums that don't have any picture yet.

Most often played albums (Ctrl+F2)

Display only albums that have been played at least once, sorted by most often played first.

Last played albums (Ctrl+F3)

Display only albums that have been played at least once, sorted by most recently played first.

Artist - Year - Genre

Sort order of the current list (other options, Year - Artist - Genre ...).

Year ascending

Choose the make the year sort ascending or descending.

Album

Update with FreeDB (Ctrl+U)

The application will automatically search for a matching album in FreeDB. You can setup which actions you want to be perform in Configuration. By default, the audio files will be tagged, the audio files will be renamed and the playlist file will be renamed too. If the process has been successful, the new album status will be orange.

Edit details (Ctrl+D)

To edit the selected album details, consult Album details edition.

Write information in playlist file

In the case your playlist files don't refer to audio files that can be tagged, artist, album, genre and year information can't be saved at a low level.
Playlists files written by Easy Album Manager in m3u file format only contains these information so use this option to replace the old playlist file with a new detailed one.

Scan album information

Update the list with the information read from the selected album audio files.
It's like launching a Full scan on a single album. Modified information not formerly saved in the audio files tags will be lost.

Paste image (Shift+Ctrl+V)

To change the selected album cover art picture. You can also drag'n'drop an image file on the cover art panel.
You can do it even if a cover art image is already displayed, the new one will overwrite the former one.
Cover arts image files are always saved as a JPEG file in the album directory, with the same name as the list file but with the .jpg extension.

Load image

Load the selected album cover art from a file.

Delete image

Remove the selected album cover art. Be careful : the file itself will be removed !

Import cover from local CoversDB (Ctrl+I)

Try to find a cover art for the selected album in the local CoversDB, and get it if it's found.

Remove album from list

Remove the selected album from the list. The next time a scan (full or fast) is performed, it will appear again.

Selection

Create a selection

A selection is a subset of your current list. You can create selections for example if several users use Easy Album Manager : this way each one can easily display his favorite albums. Unlike Filters, you build selections by selecting albums one by one.

Edit current selection (Ctrl+E)

In Edit mode, you can add albums to the current selection, for example by clicking in the check box located either in the first column (list mode) or in the left lower corner of the album panel (browse mode). You can also use the menu Add/Remove selected album (Ctrl+A) or its shortcut.

Rename selection

Renames the current selection.

Remove selection

Removes the current selection.

Add/Remove selected album (Ctrl+A)

To add or remove the selected album from the current selection.

Add all albums to selection (Shift+Ctrl+A)

To add all the albums to the selection. It's very useful for example if you have applied a filter, and want to add all the displayed albums to the current selection.

Playlist

Play album (Ctrl+P)

Clears the playlist and plays the selected album in the built-in audio player.

Play album (external)

Plays the selected album in an external audio player.

Add album to playlist (Shift+Ctrl+P)

Adds selected album tracks at the end of the built-in audio player playlist.

Add all albums to playlist

Adds all the albums at the end of the built-in audio player playlist. It may take a lot of time, because tracks length and bitrate may need to be computed !

Play track

Clears the playlist and play the 'TRACKS OF THE SELECTED ALBUM' selected track in the built-in audio player.

Play track (external)

Plays the 'TRACKS OF THE SELECTED ALBUM' selected track in an external audio player.

Add track to playlist

Adds the 'TRACKS OF THE SELECTED ALBUM' selected track at the end of the built-in audio player playlist.

Load playlist

Loads a playlist in the built-in audio player.

Save playlist

Saves the built-in audio player playlist to a file.

Clear playlist (Ctrl+Y)

Clears the built-in audio player playlist.

Remove track

Removes the built-in audio player selected track.

Move track up

Moves the built-in audio player selected track up.

Move track down

Moves the built-in audio player selected track down.

Jump to currently playing album (Ctrl+J)

If an album is currently playing, it will locate this album in the list (even if you're in browse mode).

View remote commander (Ctrl+W)

To show/hide the Remote commander.

Tools

Playlist builder (Ctrl+L)

If you want to create your album playlists, to move files, directories etc ... use the Playlist management.

Local CoversDB management (Ctrl+R)

View the content of your local CoversDB, import cover arts from other users CoversDB files ... Have a look at Covers database.

View menu bar (Ctrl+M)

In order to show/hide the main menu bar. Remember the shortcut (Ctrl+M) !

Toolbars management

If you want to setup your toolbar, choosing what to display and what to hide.


Create a new playlist

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Create a new playlist

Please enter the playlist file name, with no extension, and the playlist type (m3u, pls or b4s).


Directories to scan

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Directories to scan

Directories to scan are where the application will search for albums (playlists). After modifying the directories to scan, you will be asked to scan your list.

Move

If you have moved a directory (scanned by the application) in another location, Easy Album Manager won't find the files anymore. Click on this button to tell the application that the former location has to be replaced by the new one.


Playlist management

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Playlist management

This tool will give you the possibility to manage your playlist files (create, delete ...), but you can also move, rename, delete files, folders, playlists ...

Playlists contains tracks, and orphan audio files are files that do not belong to playlists.

1. Directories to scan

Please choose the directory to browse in window 2.

2. Directory tree view

This window browses the selected directory, in a playlist management focused view.

You can access a context menu by right-clicking on an item. Only allowed operations will be displayed in this menu.

Creating

Playlist : you can create a playlist either if you selected a directory where there are orphan audio files (that not belongs to a playlist) or if you have selected one or several orphan audio files.

Renaming (by directly editing the text in the tree)

Folder

Playlist

Track

Orphan audio file

Picture

Moving items

Folder to folder (using drag'n'drop)

Playlist to folder (using drag'n'drop) : audio files of the playlist will be moved too, if possible.

Orphan audio file(s) to playlist (using drag'n'drop) : the audio file(s) will be added at the end of the playlist.

Orphan audio file(s) to playlist track (using drag'n'drop) : the audio file(s) will be added to the playlist, after the target track.

Orphan audio file(s) to folder (using drag'n'drop)

Picture file to playlist (using drag'n'drop) : the dropped picture will not be considered as the playlist cover art.

Track(s) : inside a playlist the selected track(s) can be moved up or down.

Deleting items

Playlist : the playlist file will be removed, and its tracks will now be orphan audio files.

Track(s) : tracks are removed from the playlist and now become orphan audio files.

Picture

Editing

Playlist : in order to change the album settings (and to access FreeDB). Have a look at Album details edition.

3. View/Hide

If you have a big hierarchy, it can be useful to hide some kinds of items.


List window

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

List window

There are sliders between the different parts of the windows in order to resize these areas.

You can use the keyword (TAB key) to navigate through controls.

1. Main menu

The main menu can be hidden if you want more place for your list (or browse), have a look at View menu bar (Ctrl+M).

2. Toolbar

This toolbar can be tuned : Toolbars management.

3. Selected album cover art

Use the mouse right-click to open a context menu and modify the picture. You can also directly drag'n'drop a new picture on it.

4. List

This window displays the albums found by the scan process. You can change the way it's sorted with the sort list options.

You can view this list in a hierarchical form (folders are displayed) by clicking on the little button in the column header, or using the main menu (View folders in list (Shift+Ctrl+B)).

You can select an album by left-clicking on it, open a context menu with a mouse right-click, play directly an album by double-clicking on it.

By pressing a letter from A to Z you will reach the first album having this letter as the first artist name character. Pressing this letter again will jump to the next one.

There are two columns of dots. The first one is a "status" columns. Status can be red, orange or green. You can change the status by clicking on a dot. This status if for informative purpose, to give you a way to know which albums you need to tag or rename for example. By default, scanned albums are "red". You can change the status of you whole list by clicking on the column header. Easy Album Manager will automatically change this status only in a few cases : it will be changed to orange after applying album details or a successful Update with FreeDB (Ctrl+U).

5. Tracks

Displays the selected album tracks. The first column indicates the type of tag used in this file (1 for id3v1, 2 for id3v2, another one for wma).

You can right-click on a track to display the tracks context menu. If the text is in gray instead of black, it means that no tag has been found for the track title, and the file name has been taken instead.

Double-click on a track to play it immediatly.

6. Built-in player

Have a look at Built-in audio player.

7. Status

The status bar displays the selected album playlist file path.


Built-in audio player

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Built-in audio player

The first time an album or a track is played, its length and bitrate are computed and this may take some time.

1. List of tracks

You can right-click to open a context menu. Double-click to play a song. You can select several tracks with the mouse and move them all up or down.

2. Command panel

Previous, Play, Next ... but also loading/saving playlists, a volume slider and time/bitrate. The S button (two-states : up or down) activates or deactivates the shuffle mode.

3. Spectrum

It can be hidden, have a look at Configuration.

4. Progress bar

Indicates the current played track progress. You can click anywhere on the progress bar to go to a track position.


Browse window

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Browse window

The browse window is located at the same place as the list window. You can select an album by left-clicking on it, open a context menu with a mouse right-click, play directly an album by double-clicking on it.

You can change a cover art picture by drag'n'dropping a new picture on it.

The keyboard can be used to navigate (arrow keys).

By pressing a letter from A to Z you will reach the first album having this letter as the first artist name character. Pressing this letter again will jump to the next one.

You can change the display settings (view Browse options).

If you don't use the cover art pictures cache, the display can be long. Please have a look at Configuration to enable/disable the cache.

If cover arts are not up to date (what you see is not what you updated on the file system) you can either Scan album information or perform a Scan current list (Ctrl+F5).


Browse options

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Browse options

1. Panel size

Each album will be displayed in a panel, you can specify the panel size (width, height) and the space to put between panels.

2. Colors

Background is the browse window background color, others apply to the album panels. In selection refers to albums that belong to a user selection. Click on the colored box to change a color.

3. Misc settings

Same background in list mode : in the list mode, the area where the selected album cover is displayed can have the same color as the browse mode background.
View panel border : show/hide the album panel borders.

4. Fonts

You can change the fonts used to display the album details in the panels. Check the "3D" checkbox to enable the 3D effect, and choose the 3D color clicking on the color selection box at the right of the checkbox.

5. Presets

When you're happy with your new browse mode display settings, you can save them to presets, in order to load them later, this way you can easily access to different "looks".


Album details edition

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Album details edition

1. Album

The first line displays the album as it is currently saved in the list. If you click on it, you will have its details (in 2), its tracks (in 3) and its cover art (in 4).

If this list contains several lines, the other lines are albums that have been found on FreeDB and that are supposed to refer to the same album, with maybe better information. You can select one of them and display its details in 2 and 3 too.

If you want to change your album details (pressing the Apply button) you have to know that the information that are displayed in 2 and 3 at the moment you click on Apply will be saved.

This means that you can for example select a FreeDB album, modify information in 2 and 3, and then press Apply to save these changes.

2. Details

You can edit these fields to modify the specified information.

3. Tracks

This box lists the tracks of the album selected in 1. You can manually modify these titles if you're not happy with one of them. Once it's ok, you can Apply the changes.

When you display the currently saved album settings, when tracks appear in gray, it means that no title tag was found, and the file name is displayed instead.

4. Cover art picture

Use the buttons in order to modify the cover art picture.

5. Format and tag settings

Before pressing Apply you can choose which actions to perform :

Tag track files : the audio files tags will be modified to match the new details.
Rename track files : the audio files will be renamed to match the new details, using the default track file name (have a look at Configuration).
Rename playlist file : the album playlist file will be renamed using the default playlist format, have a look at Configuration too.
Rename directory : the directory containing the playlist will be renamed (with the same name of the playlist file, without the extension). This will work only if there is only one playlist in the directory.

It is always better to tag the audio files, so information are stored at the lowest level. You can choose which tag to use (if your audio files are mp3 only) : id3v1, id3v2 or both. You can also choose the playlist format (m3u, pls, b4s).


Search

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Search

Search string : String or words to search.

Words only / full string : The result will have to match either the search string either all the words of the search string.

Search in ... : Choose where you want the search to be performed.


Filter options

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Filter options

Filtering is used to display only albums of your list that match the following criterias.

For artist and genre, you can put several strings separated by a ';'. You can type them directly or use the '+' buttons to select them from a list.

If you put a " (double-quote) at the start of a string, album artist or genre must start with the same characters in order to match.

If your string ends with a ", album artist or genre must have the same final characters.

If your string starts and ends with double quotes, the album artist or genre must exactly match the string.

For example
rock;metal
in genre will match albums having "rock", "progressive rock", "death metal" as genre, but
"rock"
will match "rock" only and
rock"
will match both "rock" and "progressive rock" but not "rockabilly".

About the year criteria :
1970;1972
will match all albums of 1970 or 1972
-1970;1990-
will match all albums before 1970 and after 1990

You can save your filters in presets (2).


Covers database

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Covers database

The CoversDB is a cover art pictures repository. The local CoversDB is used to store pictures (you can export them from your list to the local CoversDB, but you can also import pictures from the local CoversDB to your list).

It is also possible to export your current list pictures to a CoversDB file, and share it whith your friends. They will be able to import the whole content of this CoversDB file into their local CoversDB.

The quality of the stored cover arts is displayed (can be 128x128, 256x256, 512x512). You can change the default quality before exporting your pictures to your local CoversDB in Configuration.

Menu options

Open local CoversDB : if you were looking at a CoversDB file and want to come back to your local CoversDB.
View a CoversDB file : to browse a friend's CoversDB file.
Import covers from a CoversDB file : to import the content of a friend's CoversDB file into your local CoversDB.

1. Artists

Click on an artist name to browse albums in 2. You can remove an artist with the dedicated button.

2. Albums

Click on an album title to view its covers art in 3. You can remove an album with the dedicated button.

3. Cover art picture

You can save this cover art as a Jpeg file using the button.


Cover picture replacement

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Cover picture replacement

You're asked to replace a picture by another one. If you check the Don't ask me anymore, apply for all check box then you won't be asked again for the next cover art pictures to replace.

Press on Stop if you want to stop the current process.


Remote commander

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Remote commander

The remote commander is a stay-on-top window (it will always be in your screen foreground) that gives you access to a few built-in player features.

Let your mouse over the picture if you want to have a yellow hint indicating the artist, album name, and year.

Click on the picture to show/hide the bottom command panel.


Configuration

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Configuration

General

Window

Always stay on top : Easy Album Manager window will always stay in the foreground (all other windows will be behind).
View spectrum : show/hide the spectrum in the Built-in audio player.
Show loading splash screen : show/hide the loading splash screen at the application start.
List mode cover art position : choose where the little cover art picture will be displayed in list mode.
Hide folders with one playlist : In list mode with a hierarchical view, folders having only one playlist will be hidden, in order to make the display more usable.

File name formats

Playlist file name : this format will be the default one when proposing to create/rename a new playlist. Use %artist (artist name), %album (album title) and %year (release date).
Track file name : default format when renaming a track. Use %artist, %album, %year and also %number (track number in the album) and %title (track title).

File system

Enable directories prescan : enable this in order to display a progress bar instead of the number of scanned directory in a scan process. If you're scanning a network drive, you should disable this option because the prescan can take a while.
Log performances : not necessary, used for performances improvement only.
mp3 cd autodetect and autoscan : when enabled, each time a CD is inserted in one of your players, it will be detected and scanned in order to find playlists on it. If playlists are found, a new list is automatically created and displayed.
If you saved a .cea file in the root of your medium, it will be loaded instead of the scan, you will save time !

Covers caching

Enable covers caching : in order to make the cover arts display faster, cover pictures can be cached. The picture file is loaded only the first time it is displayed, and stays in memory after. If you want to clear this cache, perform a scan from the main menu.
Quality : please choose in which quality you want the pictures to be stored in memory. The higher resolution, the better quality, but also the more memory !
Save cached covers in the .eam file : cached pictures will be stored in the .eam file (be careful, its size can be huge if you choose a high resolution !).

CoversDB default picture quality

Quality : same as above, but for CoversDB storing.

Most often / last played albums

Most often played display count : maximum number of albums to display when the "Most often played albums" sorting is selected.
Last played display count : same for the "Last played albums" sorting.

Internet

Updates

Check for updates : when enabled, the application will search for a new release on the official website each week.
URL : of the official website, by default http://easyam.free.fr.

FreeDB

Enable FreeDB search : FreeDB is a repository for album information. This way you can get artist, album name, tracks titles ... for your albums, instead of getting them from your CD sleeve, automatically in Album details edition.
URL : URL of the FreeDB server script, by default http://freedb.freedb.org:80/~cddb/cddb.cgi.
Login / Host name : required by FreeDB.

FreeDB album update

The following default values apply only to Update an album with FreeDB (Ctrl+U).

Tag track files : the audio files tags will be modified to match the new details.
Rename track files : the audio files will be renamed to match the new details, using the default track file name (have a look at Configuration).
Rename playlist file : the album playlist file will be renamed using the default playlist format, have a look at Configuration too.
Rename directory : the directory containing the playlist will be renamed (with the same name of the playlist file, without the extension). This will work only if there is only one playlist in the directory.
Tag type : choose the tag type (for mp3 files only) if you checked "tag track files".


Export

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Export

The application propose you a very powerful export process, based on templates (LibTPT, developed by Isaac W. Foraker, that implements the PML language).
If you want to write your own templates, have a look at Template editor.

Template file

The template file is a tpt file, use the button to choose it or type its name directly. Use the Edit button to edit a template or to create a new one.

Output file

Name of the output file. By default the Easy Album Manager template files have the output file type in the header, so you should always be proposed the correct extension.

Number of albums to export

You can limit the number of albums to export, for example to test your templates : it can be long to export the whole !

Open the result file after the export

Automatically open the generated file, usually the output file extention is sufficient to define the good application to launch.


Template editor

Index | Create a new playlist | Directories to scan | Playlist management | List window | Built-in audio player | Browse window | Browse options | Album details edition | Search | Filter options | Covers database | Cover picture replacement | Remote commander | Configuration | Export | Template editor

Template editor

This feature is more dedicated to power users. You can edit templates in order to modify them to your specific needs, or write new templates. For details about the language, have a look at LibTPT, developed by Isaac W. Foraker. I put a copy of the "LibTPT book" below.

Easy Album Manager specific use

The first line of your scripts must indicate the output file type, for example
@# SQL file(*.sql)|*.sql
or
@# Text file(*.txt)|*.txt
More generally :
@# Name of the format (*.ext)|*.ext
where ext is your extension.

Please use the progress function to indicate to Easy Album Manager at which step the process is.

I added a few functions to the standard library :
htmlescape(string) : transforms special characters in order to make them HTML compliant
xmlescape(string) : same for XML
filename(string) : extracts and returns the file name (with its extension) from a full path
filepath(string) : extracts the path from a full path
progress(step,over) : indicates to Easy Album Manager at which step from completion the process currently is

About data structures passed to the template, the main object is the albums array.

Properties of an album :
artist (string)
album (string)
genre (string)
year (string)
playlistpath (string)
coverpath (string)
tracks (array)

Properties of a track :
title (string)
trackpath (string)

The best way to do a good job is to have a look at default tpt files !

The LibTPT Book

A Template Language for C++

Isaac W. Foraker

Copyright © 2002-2003 Isaac W. Foraker

Abstract

This is for the LibTPT template scripting language for C++, based on build 1.20. For the most up to date documentation, go to http://tazthecat.net/~isaac/libtpt/.

Table of Contents

Introduction
What is LibTPT?
Why LibTPT?
Who needs LibTPT?
1. Compilation and Installation
Supported Platforms/Compilers
Where to get LibTPT
Building on Windows
Building on Unix
2. The TPT template language
A quick sample
Reserved Characters
Variables
Comments
Expressions
Whitespace & Carriage Returns
Macros
3. The C++ Interface
A quick sample
4. Writing a TPT callback function
What is a callback?
Uses for Callbacks
The Callback Interface
TPT Callbacks and Security
A. TPT Reference
Preprocessor control
@# comment
#tpt-preproc-ignoreindent
#tpt-preproc-ignoreblankline
#tpt-preprocessor-ignorespace
@include
@includetext
Setting Variables
@set
@setif
@unset
@push
@pop
Conditional Parsing
#tpt-if-else
Loops
@while
@foreach
String Functions
#tpt-compare
@concat
@substr
@length
@empty
@lc
@uc
@lpad
@rpad
@repeat
Math Functions
@avg
@sum
Array Functions
@isarray
@size
Hash Functions
@ishash
@keys
General Functions
@eval
@rand
B. C++ Reference
Namespace TPT
Classes
TPT::Parser
TPT::IParser (1.2+)
TPT::Buffer
TPT::Symbols
TPT::Object
C. Converting from PML to TPT
Strings
Carriage returns
Functions
Unsupported PML
D. Project Specifics
License
Credits
Reporting bugs

List of Examples

2.1. helloworld.tpt
2.2. Contents of a fruit basket
2.3. A fruit basket array
2.4. Random array index
4.1. #example-fsum
C.1. Strings in PML and TPT
C.2. Carriage Returns in PML and TPT

Introduction

Table of Contents

What is LibTPT?
Why LibTPT?
Who needs LibTPT?

What is LibTPT?

TPT is a template scripting language implemented in C++, designed to be integrated with C++ programs. It is intended as a fast, lightweight replacement for fullblown scripting languages, providing an easy interface for embedding TPT scripts in C++ code. The TPT language was originally based on PML.

Known uses for TPT include generating CGI web pages, C and C++ source code, Make files, and e-mail messages.

Why LibTPT?

I find many of today's template languages frustrating and hard to work with. Originally, I simply wanted to perform on-the-fly variable substitution, but as my needs grew, so did the idea for TPT. For a time, I used the PML language, but that was written entirely in Perl and lost the support of its creator.

Though I initially only intended to use TPT for generating HTML responses for CGI scripts, it was quickly adopted by the clo++ project for C++ code generation, and I have since used it for generating E-mail, Makefiles, and C source code as well.

Who needs LibTPT?

As with most language choices, the decision to use TPT is usually a matter of personal tastes.

One important point to note is that TPT is not about I/O. It is optimized for output only (like generating source files or web pages), so if you are designing interactive applications, TPT is not for you.

However, if you are looking for a simple solution for generating customized text files, give TPT a try.

Chapter 1. Compilation and Installation

Table of Contents

Supported Platforms/Compilers
Where to get LibTPT
Building on Windows
Building on Unix

Supported Platforms/Compilers

LibTPT has been compiled and tested under the following platforms:

FreeBSD 4.5 GCC 3.x
Linux GCC 3.x
Win32 MSVC 6.0

LibTPT is also rumored to build on:

Sparc Solaris Forte C++
Sparc Solaris GCC 3.x
Mac OS X GCC 3.x
Win32 MSVC++.Net (VC 7.0)

Where to get LibTPT

http://tazthecat.net/~isaac/libtpt/download.cgi

Building on Windows

Currently, LibTPT officially supports Microsoft Visual C++ 6.0, but is known to work with Visual C++.Net (7.0) as well. For optimal performance, it is highly recommended that you install the STLPort (http://www.stlport.org/).

After installing the STLPort, add the following line to %INCLUDE%\stlport\stl_user_config.h:

#define _STLP_DO_IMPORT_CSTD_FUNCTIONS 1

The %INCLUDE% variable is the path where the stlport directory was installed. This will make the STL import the standard C library functions into the "std" namespace, making Visual C++ act more like a standard C++ compiler.

Make sure you set %INCLUDE%\stlport as your first include path, or the wrong version of the header files will be included. Also, since MSVC 6 does not properly handle the standard library in the std namespace, avoid broad statements like

using namespace std;

Once your build environment is set up correctly, open w32/libtpt.dsw. The libtpt workspace includes all projects necessary to build libtpt and its tests. The default build configuration is intended for a generic x86 platform. Change these options if you so desire.

Both debug and release configurations are available for build. Each project should build with "debug" in its name when compiled as a debug project.

Batch build all the release versions, then run tests:

cd test/
test.bat

Building on Unix

At the time of the writing of this document, LibTPT has only been tested with GCC 3.x. GCC 2.95.x is known to have problems compiling LibTPT.

The LibTPT configuration system requires Perl 5.005 or later. The configure.pl script requires that either the CXX environment variable is set to the path of your C++ compiler, or that you specify the path to you C++ compiler with the --cxx command line option.

./configure.pl --cxx /path/to/g++ [--help]
make
./test.sh
make install

By default, configure.pl will use /usr/local as the install directory. Use --prefix=/new/install/path to override this.

Chapter 2. The TPT template language

Table of Contents

A quick sample
Reserved Characters
Variables
Comments
Expressions
Whitespace & Carriage Returns
Macros

This introduction to the TPT template language is intended for users who are already familiar with programming. If you are not familiar with the concepts of numbers, strings, arrays, functions, and expressions, you may want to read an introductory level programming book.

A quick sample

Example 2.1. helloworld.tpt

@set(hello_world, "Hello World!")\
@# Output Hello World or the value of ${hello_world} if it is set
@if (@empty(hello_world)) {
Hello World!
} @else {
${hello_world}
}

Reserved Characters

TPT reserves the following characters.

@ { } " ' \

To use one of these characters in text, use the backslash (\) escape character. For example, \\ in TPT will evaluate to a single \. Not escaping these reserved characters can lead to undesirable effects.

Variables

Variables are objects that hold values. In TPT, a variable may hold a value of type integer, string, array of values, or hash of values.

A variable in TPT is identified in plain-text as ${id} and in an expression as just id, where id is the name of the variable. The value of a variable is set using the @set TPT command.

@set(id, 123)

@set(id, "The red fox runs.")

A variable may also be cleared using the @unset TPT command.

@unset(id)

See Example 2.2 for an example of how variables may be used in a template.

Example 2.2. Contents of a fruit basket

Listing of fruitbasket.tpt

@set(fruit, "Apple")
@set(basket, 12)
The basket holds ${basket} ${fruit}s.

Output of fruitbasket.tpt

The basket holds 12 Apples.

Variables can also hold more complex values, such as arrays or hashes. Array variables look like,

${array[index]}

and hashes look like,

${array.member}

In arrays, the index can be either a number or an expression that evaluates to a number. Example 2.3 demonstrates how to set a variable to an array, then read the variable.

Example 2.3. A fruit basket array

Listing of fruity.tpt

@set(basket, "apple", "orange", "lime", "banana", "pear")\
The fruit basket contains \
@foreach fruit (basket) { ${fruit} }.

Output of fruity.tpt

The fruit basket contains apple orange lime banana pear .

Note the use of spaces in this example. Backslashes are used to join lines. For more details about controlling whitespace and carriage returns, see the section called “Whitespace & Carriage Returns”.

Example 2.4 demonstrates how to use an array index in a creative fashion.

Example 2.4. Random array index

Listing of randfruit.tpt

@set(basket, "apple", "orange", "lime", "banana", "pear")\
The fruit of the day is ${basket[@rand(@size(basket))]}.

Possible output of randfruit.tpt

The fruit of the day is banana.

To determine the type of variable, use @isarray, @isscalar, and @ishash.

Comments

Comments are denoted by the @# (at-pound) symbols. TPT only supports to end-of-line comments. I.e. everything on the line following @# is a part of the comment.

Hello World!	@# This is the Hello World Comment.

In the above example, everything after Hello World! will be ignored by the TPT parser, including the whitespace. Comments affect whitespace depending on use. All whitespace immediately preceeding a comment is ignored. In the case of a full line comment,

@# This is a full line comment
    @# This is not

the entire line, including carriage returns, is ignored. In order to be classified as a full line comment, @# must be the very first characters on the line. Preceding the @# with whitespace will only cause the whitespace and comment to be ignored. This is useful if you need to insert a certain number of blank lines into a template.

@# Insert some blank lines
    @# blank line 1
    @# blank line 2
    @# blank line 3
    @# blank line 4
    @# blank line 5

Expressions

Expressions in TPT can only be executed when placed inside a TPT wrapper like a function, macro, array [], loop, or conditional expression. TPT employs a full Recursive Descent parser, so complex infix expressions are supported. Use @eval to evaluate an expression in text.

Whitespace & Carriage Returns

Since the primary purpose of TPT is to format templates into text, controls are provided to remove whitespace and carriage returns. Using a backslash (\) at the end of a line will join lines. Any whitespace before @< will be ignored, and any whitespace after @> will also be ignored.

Macros

Macros are a powerful feature of TPT. User defined Macros in TPT are very similar to user defined functions or subroutines in other languages. A macro must be defined before it is used. A macro definition looks like:

@macro(mymacro, param1, param2, ...) {
    macro body
}

To access this macro once its defined would look like:

@mymacro(param1, param2, ...)

Chapter 3. The C++ Interface

Table of Contents

A quick sample

A quick sample

dumptpt.cxx

#include <libtpt/tpt.h>
#include <iostream>
#include <stdexcept>

// Dump the parsed template output straight to std::cout
void dumptemplate(const char* filename)
{
    try {
        // Instantiate a parser
        TPT::Parser p(filename);

        // Add an include path (only ./ searched by default)
        p.addincludepath("./include");

        // Parse the template directly to standard output
        if (p.run(std::cout))
        {
            // handle reporting of template errors
        }
    } catch(const std::exception& e) {
        std::cout << "EXCETPION: " << e.what() << std::endl;
    }
}

Chapter 4. Writing a TPT callback function

Table of Contents

What is a callback?
Uses for Callbacks
The Callback Interface
TPT Callbacks and Security

What is a callback?

In C++, it is sometimes handy to specify that a library function call a user defined function for customizable behavior. In the standard library, the generic binary search and quick sort functions do this.

void *bsearch( const void *key, const void *base, size_t num, size_t width, int
    (*compare ) ( const void *elem1, const void *elem2 ) );
void qsort( void *base, size_t num, size_t width, int (*compare )(const void
    *elem1, const void *elem2 ) );

Each of these functions allows the user to specify a custom compare function for a user defined data type. LibTPT provides a similar method to allow the user to specify a C++ function that will be called from a TPT template.

Uses for Callbacks

Callbacks give the user the power to extend TPT beyond its core functionality. For instance, a project may require TPT to do some floating point math, which is not available in the core language. On the more extreme, a user may decide to extend TPT with CGI or Database functionality. Whatever the reason, callbacks let the user implement fast TPT functions within the C++ code.

Remember, while it is tempting to write callback modules that allow TPT to do anything a full blown language can do, TPT was designed to take advantage of the speed of C++ for variable management. Therefore, functionality like database access or CGI processing should remain in your C++ code for optimal performance.

The Callback Interface

A TPT callback must be declared in the form:

    bool mycallback(std::ostream& os, TPT::Object& params);

Note that the first parameter is a reference to an output stream. All communication between the callback and the LibTPT parser are handled with streams. So, to have the callback print a message would look like:

    os << "My Message";

The second parameter is of type TPT::Object, which represents a generic object in LibTPT. The object may hold a type of scalar, array, or hash. The params variable passed to the callback is guaranteed to hold an array, but that array may hold scalars, arrays, hashes, or any combination of those types, depending on how the callback was called from within the TPT template. The enumerated types of object available to a callback function are TPT::Object::type_scalar, TPT::Object::type_array, and TPT::Object::type_hash, with the corresponding access methods TPT::Object::scalar(), TPT::Object::array(), and TPT::Object::hash(). If a call to the incorrect access method is made, an exception will be thrown. The parser does its best to handle these exceptions without interrupting the template translation.

When accessing a member of Object::array() or Object::hash(), be sure to use the get() method to get the member's real address. Member of Object arrays and hashes are stored in a smart pointer to ensure proper memory management. Refer to the example below for how to properly access a member of an Object array.

As mentioned earlier, TPT does not have any built-in functionality for dealing with floating point numbers. Suppose you needed a function to sum a list of floating point numbers populated into variables from a database or user form. See Example 4.1 for an example of what the code might look like for a floating point summation function.

Example 4.1. A callback example: @fsum()

#include <libtpt/tpt>
#include <ostream>

// Define a function for summing floating point numbers
bool fsum(std::ostream& os, TPT::Object& params)
{
    // Make a reference to the array for easier typing.
    TPT::Object::ArrayType& pl = params.array();
    // initialize the work variable
    double work=0;

    // Set up iterators and loop.
    TPT::Object::ArrayType::const_iterator it(pl.begin()), end(pl.end());
    for (; it != end; ++it)
    {
        // Make a reference to the object for easier typing.
        TPT::Object& obj = *(*it).get();
        // Only add the object if it is a scalar.
        if (obj.gettype() == TPT::Object::type_scalar)
            work+= atof(obj.scalar().c_str());
        else
            return true; // expected a scalar!
    }
    os << work;
    return false;
}

This callback is then registered with the TPT::Parser::addfunction() method.

    TPT::Parser p(buf);
    p.addfunction("fsum", &fsum);

The above example demonstrates how simple it is to loop through an array of scalar examples. As an exercise, modify fsum to be able to process sub-arrays of floats.

TPT Callbacks and Security

As with most programming interfaces, using TPT callbacks can open some serious security holes if you are not paying attention. It is recommended that you do not create callbacks that can execute arbitrary programs, and when processing user input, always bounds check the input. Bounds checking is already handled by the std::string class, so the best bet is to stick with std::string. Do not use sprintf for formatting strings. If you must format a string, and absolutely cannot use iostreams, use snprintf instead, and double check your format string for any errors.

Appendix A. TPT Reference

Table of Contents

Preprocessor control
@# comment
#tpt-preproc-ignoreindent
#tpt-preproc-ignoreblankline
#tpt-preprocessor-ignorespace
@include
@includetext
Setting Variables
@set
@setif
@unset
@push
@pop
Conditional Parsing
#tpt-if-else
Loops
@while
@foreach
String Functions
#tpt-compare
@concat
@substr
@length
@empty
@lc
@uc
@lpad
@rpad
@repeat
Math Functions
@avg
@sum
Array Functions
@isarray
@size
Hash Functions
@ishash
@keys
General Functions
@eval
@rand

Preprocessor control

The following functions affect the flow of the Lexical Analyzer, and are never parsed.

@# comment

Ignore everything until the end of the line. If the comment is the first item on the line, the entire line will be ignored.

@# This is a whole line comment, so this line will be ignored
    @# This is not

@mymacro(a, b, c)	@# describe my macro

@tpt_ignoreindent, @tpt_noignoreindent

When @tpt_ignoreindent is called (with no parenthesis), all indentation on the following lines will be ignored. Use @tpt_noignoreindent to stop ignoring indentation.

@itpt_ignoreindent\
    @if (x) {
        Four score and seven years ago...
    } @else {
        We the people of the United States...
    }

Note: @ignoreindent and @noignoreindent are depricated.

@tpt_ignoreblankline, @tpt_noignoreblankline

When @tpt_ignoreblankline is called (with no parenthesis), any line with no content (including white-space) will be ignored.

@tpt_ignoreblankline\
@macro1() {...}

@macro2() {...}

@macro3() {...}

@tpt_noignoreblankline

Note: @ignoreblankline and @noignoreblankline are depricated.

@<, @>

The ignore space operators instruct the lexical analyzer to ignore any space preceding @<, or any space following @>.

@# ignore spaces after @>
@>	This should be flush to the left
@# ignore spaces before @<
    @<This should be flush to the left

@include

Include and parse a TPT header file, usually a filename ending in .tph.

@include("macros.tph")\
@include('heading.tph')\

@includetext

(Version 1.2+)

Include a raw text file without parsing. This is useful when including some kind of raw statement, like a license agreement.

@includetext("license.txt")\

Setting Variables

@set

Assign a value or values to a variable.

@set(identifier, expression)

@set(identifier, expression1, expression2, ...)

@setif

Assign a value or values to a variable only if the variable is empty.

@set(identifier, expression)

@set(identifier, expression1, expression2, ...)

@unset

Clear a variable.

@unset(identifier)

@push

Push a value onto the back of an array.

@push(identifier, expression)

@pop

Pop a value off the back of an array.

@pop(target identifier, array identifier)

Conditional Parsing

@if/@elsif/@else

Perform conditional processing.

@if (expression) {
    conditional block
} @elsif (expression) {
    conditional block
} @elsif (expression) {
    conditional block
} @else {
    conditional block
}

Loops

@while

Loop over a block of code while the loop expression is true.

@while (expression) {
    loop block
}

@foreach

Loop over an array, assigning the value of the current index to the specified identifier on each iteration.

@foreach identifier (array) {
    loop block
}

String Functions

@compare, @comp, @strcmp

Compare two strings, giving -1 if string1 is less than string2, 0 if string1 is equal to string2, or 1 if string1 is greater than string 2. @comp and @strcmp are aliases for @compare.

@concat

Concatenate a list of strings together, and return the new string.

@set(newstring, @concat("prefix", "suffix"))

@substr

Get a substring of the given string.

@# Extract one character from the alphabet
@set(x, "abcdefghijklmnopqrstuvwxyz")\
@set(i, 9)\
@substr(x, i, 1)

This sample will return "j" from the x symbol.

@length

Give the length of the given string.

@if (@length(x) > 80) {
    x is too long
}

@empty

Return 1 if string is empty or 0 if string is not empty. If given a hash or array, @empty will report an error and return nothing.

@if (@empty(x)) {
    @set(x, "[empty]")\
}

@lc

Give the lowercase version of the given string.

@if (@compare(@lc(x), "foo")) {
    x is not foo
}

@uc

Give the uppercase version of the given string.

@if (@compare(@uc(x), "FOO")) {
    x is not FOO
}

@lpad

(1.1+)

Pad the left side of the specified string with spaces until the string is the specified width. If the string is already greater than or equal to the specified width, @lpad simply returns the original string.

@lpad(string, width)

@rpad

(1.1+)

Pad the right side of the specified string with spaces until the string is the specified width. If the string is already greater than or equal to the specified width, @rpad simply returns the original string.

@rpad(string, width)

@repeat

(1.2+)

Repeat the specified text or expression the specified number of times. Any repeat value of 0 or less will produce nothing.

@# Fill the next line with a solid line of dashes
@repeat("-", 80)

Math Functions

@avg

Get the average of the specified list of integers. Numbers may be passed as part of an array, or individually as parameters. The result will be returned as a truncated integer (i.e. the result will always be rounded down).

@set(numlist, 1, 2, 3)\
@avg(numlist)
@avg(1, 2, 3)

@sum

Get the sum of the specified list of integers. Numbers may be passed as part of an array, or individually as parameters.

@set(numlist, 1, 2, 3)\
@sum(numlist)
@sum(1, 2, 3)

Array Functions

@isarray

Check a variable to see if it holds an array. Gives 1 if the variable is array, or 0 if the variable holds a different type or is not defined.

@if (@isarray(x)) {
    x is an array
}

@size

Get the size of an array. Given a scalar, @size will return 0 if the scalar is an empty string (i.e. ""). Given a hash, @size will return the number of keys and values in the hash. So, a hash with 2 keys will have a size of 4.

When given multiple parameters, @size will return the sum of the sizes of all parameters.

@size is not recursive. The sum returned by @size will not include the sizes of sub-arrays or hashes.

Hash Functions

@ishash

Check a variable to see if it holds a hash. Gives 1 if the variable is a hash, or 0 if the variable holds a different type or is not defined.

@if (@ishash(x)) {
    x is a hash
}

@keys

Populate the specified array (parameter 1) with the keys from the specified hash (parameter 2).

@keys(keylist, myhash)\
@foreach key (keylist) {
    ${key} = ${myhash.${key}}
}

General Functions

@eval

Evaluate the given expression and give the result of the evaluation.

The sum is @eval(x+y+z).

@rand

Give a pseudorandom 32-bit integer. @rand can be given a modulus to reduce its range. For example @rand(10) will return a number between 0 and 9.

@set(x, @rand())
    or
@set(x, @rand(modulus))

Appendix B. C++ Reference

Table of Contents

Namespace TPT
Classes
TPT::Parser
TPT::IParser (1.2+)
TPT::Buffer
TPT::Symbols
TPT::Object

Namespace TPT

All LibTPT library classes, functions, and variables exist in the TPT C++ namespace.

All TPT header files can be included with:

#include <libtpt/tpt.h>

Classes

TPT::Parser

#include <libtpt/parse.h>

The TPT::Parser class is the primary interface to the TPT library. For basic template processing, TPT::Parser is the only class you will need.

Parser(const char* filename);
Parser(const char* filename, const Symbols& st);
Parser(const char* buf, unsigned long size);
Parser(const char* buf, unsigned long size, const Symbols& st);
Parser(Buffer& buf);
Parser(Buffer& buf, const Symbols& st);

TPT::IParser (1.2+)

#include <libtpt/iparse.h>

The TPT::IParser class is the Interactive version of the TPT::Parser class. This version writes updates to the Symbols table back to the Symbols table passed in by the user. This is useful when there is a need to maintain state information between processing templates, or to pass state information back to the calling C++ program.

IParser(const char* filename, Symbols& st);
IParser(const char* buf, unsigned long size, Symbols& st);
IParser(Buffer& buf, Symbols& st);

TPT::Buffer

#include <libtpt/buffer.h>

The TPT::Buffer class is the base IO class for reading TPT source. Instantiating a TPT::Buffer directly is a useful optimization when you will be parsing the same template repeatedly. A TPT::Buffer is not required to parse a TPT template.

explicit Buffer(const char* filename);
explicit Buffer(std::istream* is);
explicit Buffer(const char* buffer, unsigned long size);
explicit Buffer(const Buffer& buf, unsigned long start, unsigned long end);

TPT::Symbols

#include <libtpt/symbols.h>

The TPT::Symbols class may be used to predefine a symbols table for a TPT template before the template is passed to TPT::Parser. The TPT::Symbols object must be populated before it is passed to the TPT::Parser. A TPT::Symbols table is not required to parse a TPT template.

TPT::Object

#include <libtpt/object.h>

The TPT::Object class is intended for intermediate to advanced users. The TPT::Object is the internal representation of data used within LibTPT. TPT::Object is designed with speed and exception safety in mind.

TPT::Object is designed to hold generic data including scalars or strings, arrays, and hashes. TPT::Objects are versatile, so an array or hash container may hold another array or hash container. The gettype() method is used to determine the type of Object being stored, and the either the scalar(), array(), or hash() method is used to access the object. If the incorrect accessor is used, TPT::Object will throw an exception.

There are two basic uses for TPT::Object in your code. First, to access variables passed to a user defined callback function. Second, to set up complex data structures before entering the TPT Parser.

Appendix C. Converting from PML to TPT

Table of Contents

Strings
Carriage returns
Functions
Unsupported PML

Strings

In PML, strings may be passed bare (i.e. without quotes) to macros and functions. TPT requires strings to be in enclosed in either single or double quotes (' or ").

Example C.1. Strings in PML and TPT

String parameters in PML

@include(file.pmlh)

String parameters in TPT

@include("file.tph")
or
@include('file.tph')

Carriage returns

TPT does not automatically remove carriage returns on lines that only contain function calls. To make TPT ignore the carriage return, use a backslash.

Example C.2. Carriage Returns in PML and TPT

PML ignores carriage returns

@include(file.pmlh)

TPT must be told to ignore carriage returns

@include("file.tph")\

Functions

@concat is different in TPT. @concat concatenates a variable list of strings together, with no added spaces. The PML version concatenated values onto an existing symbol.

PML: @concat(id, value)

TPT: @set(id, @concat(id, "value"))

"value" may be either a string or an expression.

The new @concat also replaces prepend and append. Instead use:

PML: @prepend(id, value)

TPT: @set(id, @concat("value", " ", id))

PML: @append(id, value)

TPT: @set(id, @concat(id, " ", "value"))

Why is this different? Most functions in TPT are designed to be usable within the expression processor. Some functions of PML, like concat, prepend, and acted on a symbol, instead of returning a value that could be used by the expression parser.

TPT adds the following new functions for your pleasure.

@lc(expr) - lowercase string or expression
@uc(expr) - uppercase string or expression
@length(expr) - get number of characters in string or expression

Unsupported PML

@need keyword supported by PML for loading PML modules.
@perl keyword for eval'ing perl expressions.
@unless keyword. Just use if (!expr) instead.
@until keyword. Just use while (!expr) instead.
@rib keyword for default value. Just use @else { nbsp; } for now. Another workaround is to use if (@empty(var)) if you were using @rib to only test a variable.
${ARGV} array variable.
@append keyword for appending string to a symbol. Just use new @concat.
@prepend keyword for prepending string to a symbol. Just use new @concat.

Appendix D. Project Specifics

Table of Contents

License
Credits
Reporting bugs

License

LibTPT Template Language for C++
Copyright (C) 2002-2003 Isaac W. Foraker (isaac(at)tazthecat.net)
All Rights Reserved

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

  2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

  3. Neither the name of the Author nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Credits

LibTPT Primary Programming and Documentation

  • Isaac W. Foraker (http://tazthecat.net/~isaac/)

Original PML Language, clo++ command line parser generator, and cxxtools

  • Peter J. Jones (http://pmade.org/pjones/)

Reporting bugs

If you encounter a bug in the LibTPT, please send an e-mail to isaac(at)tazthecat.net.